Skip to content

feat(runtime): fill MicroVMRuntime lifecycle methods (RIG-2493) - #719

Merged
mattwilkinsonn merged 3 commits into
mainfrom
compass-runner/rig-2493-u4-microvm-lifecycle
Aug 30, 2026
Merged

feat(runtime): fill MicroVMRuntime lifecycle methods (RIG-2493)#719
mattwilkinsonn merged 3 commits into
mainfrom
compass-runner/rig-2493-u4-microvm-lifecycle

Conversation

@rigel-mintaka

@rigel-mintaka rigel-mintaka commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

This PR is part of a stack containing 4 PRs:

  1. main
  2. feat(guestd): replace the Health-only stub with the V2b in-guest supervisor (RIG-2493) #701
  3. feat(runtime): host GuestExec layer + portable exit-signal error type (RIG-2493) #702
  4. "feat(runtime): fill MicroVMRuntime lifecycle methods (RIG-2493)" (this PR)
  5. test(runtime): shared ContainerRuntime contract suite across both backends (RIG-2493) #720

U4 of the frozen microVM Runner V2b plan (docs/designs/infra/runtime/compass-elastic-session-runtime/microvm-v2b-guest-supervisor-exec.md, Plan U4 / (c)/(d)/(e)). Fills the eight typed-error MicroVMRuntime stubs behind their frozen ContainerRuntime signatures against the V2a boot harness + the U3 GuestExec layer.

Refs RIG-2493

Co-authored-by: Matt Wilkinson matt@rigel.build

@linear-code

linear-code Bot commented Aug 28, 2026

Copy link
Copy Markdown

RIG-2493

@github-actions

github-actions Bot commented Aug 28, 2026

Copy link
Copy Markdown

Compass engineering docs preview: https://compass-runner-rig-2493-u4-m.compass-eng-docs.pages.dev

Deployed from compass-runner/rig-2493-u4-microvm-lifecycle at 1975856.

@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u4-microvm-lifecycle branch 2 times, most recently from c4480be to 56eed91 Compare August 28, 2026 07:15
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u3-host-exec branch from 869399a to 81856f8 Compare August 28, 2026 10:09
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u4-microvm-lifecycle branch from 56eed91 to b95a89a Compare August 28, 2026 10:11
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u3-host-exec branch from 81856f8 to 417292b Compare August 28, 2026 11:09
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u4-microvm-lifecycle branch from b95a89a to 9f07047 Compare August 28, 2026 11:11
rigel-mintaka and others added 3 commits August 29, 2026 15:25
…rvisor (RIG-2493)

U2 of the frozen microVM Runner V2b plan (`docs/designs/infra/runtime/compass-elastic-session-runtime/microvm-v2b-guest-supervisor-exec.md`, §Plan U2 / §(b)). Replaces the V2a `healthService` (which U1 left embedding `UnimplementedGuestControlHandler` to satisfy the widened interface) with the full `supervisor` implementing every `GuestControl` RPC.

### What

- **State gate** (`booting → ready → provisioned`, mutex-guarded): `Exec`/`ExecStream` refuse with `FailedPrecondition` until `Provision` opens the gate.
- **`Provision`** records `default_exec_uid` (validated non-zero) + `base_env`; a non-empty `nft_script` answers `Unimplemented` (V3's); a second call or a not-ready guest answers `FailedPrecondition`.
- **`Exec`** (one-shot): uid resolve (absent → session default, `0` → refused), env merge (exec keys win), stdin via `bytes.Reader` never argv, 8 MiB-capped stdout/stderr buffers (`ResourceExhausted` on overflow — the acknowledged divergence from the podman contract, OQ-E), guest-side timeout, non-zero exit is a **successful** `ExecResponse`, ctx-cancel → SIGKILL + reap.
- **`ExecStream`** (bidi): first frame must be `StartExec`; `ExecStarted` is emitted first; a shared send-mutex serializes the demuxed `stdout`/`stderr`/`ExecExit` down-frames; stdin frames + `StdinClose` half-close the child; a broken stream or ctx-cancel → SIGKILL + reap; the terminal `ExecExit` always comes from our own reap.
- **`Signal`**: `exec_id` → process-group signal; unknown/exited exec → no-op success; empty `exec_id` → `initiateStop` (the §(d) guest-stop path).
- **Stop → power-off**: `run()` derives a serving ctx wired to `stopServing`; after serve returns, an RPC-triggered stop with no serve error calls `powerOff()` (`syscall.Reboot(LINUX_REBOOT_CMD_POWER_OFF)`), the PID-1-legal shutdown. The Unix-signal path (`cmd/compass-guestd` `signal.NotifyContext`) is a **distinct** trigger and returns as before, per §(d).
- **Peer-CID guard**: `peerCIDListener` refuses any non-host CID before the first HTTP byte (hermetic non-vsock listeners are allowed); the handler carries `WithReadMaxBytes(16 MiB)` (OQ-E).
- **Boot nonce**: `cmdline.go` parses `compass.boot_nonce=<hex>` (absent → nil, empty/non-hex → error); the supervisor echoes it on `HealthResponse.boot_nonce` (U1's additive field) so Start binds the guest to the VM it launched (§(e)).

Boot steps 1–4 are byte-identical; only the serve step is retyped to `*supervisor` and gains the `powerOff` seam.

### Verification

`go build ./...` clean (whole module); `go test ./internal/guestd/...` ok; `go test -race ./internal/guestd/...` ok; `gofmt -l internal/guestd/` clean. The hermetic suite (`supervisor_test.go`) drives an in-memory h2c listener with real host child processes and covers every §(b) acceptance row (gate refusal, uid-0 refusal, default-uid resolution, stdin-not-argv, env merge, non-zero-exit success, stream demux ordering, signal-kills-live-child, signal-on-exited no-op, broken-stream reap, peer-CID pure function, RPC-stop → power-off).

### Guest PATH resolution (CI fix, folded)

`buildChild` spawned via `exec.Command(argv[0], …)`, whose bare-name resolution runs `LookPath` against guestd's OWN process environment — and guestd is PID 1 with no `PATH`, so a bare `argv[0]` (`echo`, `sh`, and in production `compass-agent`) never resolved: the first live KVM boot failed the exec rows with `executable file not found in $PATH`. The hermetic suite false-greened because it runs in-process with the test's ambient `PATH`. Fix (the container-baked-PATH analog, §(b)): `mergeEnv` floors a default `PATH=/bin:/usr/bin:/sbin:/usr/sbin` when neither the session base env nor the exec env supplies one, and `buildChild` resolves `argv[0]` against that merged `PATH` (via `resolveProgram`, honoring the session env, not the process env) — a name with a slash is used as-is, so absolute-path execs are unchanged. Regression: `TestExecResolvesBareCommandViaSessionPATH` (a base_env PATH pointing at a probe absent from the process PATH; fails before the fix) and `TestMergeEnvFloorsDefaultPATH`.

Ledger-impact: none

Spec-impact: none. Refs RIG-2493

Co-authored-by: Matt Wilkinson <matt@rigel.build>
… (RIG-2493)

U3 + U3b of the frozen microVM Runner V2b plan (`docs/designs/infra/runtime/compass-elastic-session-runtime/microvm-v2b-guest-supervisor-exec.md`, §Plan U3/U3b, §(c)/§(e)). The host-side client half of the exec control plane: a `GuestExec` layer over U1's generated `GuestControl` client, plus the backend-portable error type the runner's kill-classifier keys on.

### U3b — portable exit-signal error (`internal/runtime/exit_status_error.go`, new)

`ExitStatusError{Code int; Signal syscall.Signal}` with `Error()`, in package `runtime`. A remote guest exec cannot forge an `*exec.ExitError`, so the microVM `waitFunc` constructs this instead for a signalled guest exit. `internal/runner/agent_exec.go`'s `isDeliberateKill` is widened to `errors.As` on `*runtime.ExitStatusError` **first** (a non-zero signal ⇒ deliberate kill), then the existing `*exec.ExitError` SIGKILL branch **unchanged** — so the podman byte-path is byte-identical and only the microVM backend gets the new classification.

### U3 — GuestExec layer (`internal/runtime/microvm/exec.go`, new)

Plain structs (`ExecCall`/`ExecResult`/`StreamCall`/`ExitStatus`) mirror the proto so `runtime` types don't leak into `microvm` (`microvm` must not import `runtime`; U4 makes `runtime` import `microvm`).

- **`Exec`** (one-shot RPC): a non-zero exit is a successful `ExecResult`; a refusal/transport failure is an error; a host-side timeout → `*microvm.TimeoutError`.
- **`ExecStream`** (bidi): opens the stream, sends `StartExec`, **awaits `ExecStarted`** before returning; per-exec goroutines pump the `Stdin` pipe → stdin frames (`Close` → `stdin_close` + `CloseRequest`) and demux `stdout`/`stderr` response frames onto `io.Pipe` read ends, closing them on `ExecExit`.
- **`GuestStream.Kill`** issues a `Signal` RPC bounded by `killSignalTimeout` (never blocks teardown past it); **`Wait`** blocks on the demux goroutine and returns `ExitStatus{Code,Signal}`. A ctx-cancel stream break reports SIGKILL — guestd reaps the child bound to the broken stream.

### `podman.go` — funcs-backed ChildHandle

Adds unexported `newChildHandleFuncs(kill, wait func() error) *ChildHandle` plus `killFunc`/`waitFunc` fields. `Kill`/`Wait`/`Terminate` branch to the funcs path when `killFunc != nil`, else drive the original `cmd`/`cancel` path **untouched** (podman byte-unchanged). `Terminate` = kill then wait, returning the wait error (the exit status) when non-nil else the kill error — so a crash-vs-teardown consumer gets the exit signal.

### Verification

`go build ./internal/runtime/... ./internal/runner/...` clean; `go vet` clean over `runtime`, `runtime/microvm`, `runner`. Tests (all hardware-independent, no `microvm` build tag, no KVM):

- `exec_test.go` — fake `GuestControl` server on a unix listener over h2c Connect, dialed by a real client: one-shot non-zero exit is success + spec mapping; refusal is an error; one-shot timeout → `*TimeoutError`; stream demux ordering (interleaved frames land on the correct pipes, drained concurrently); stdin framing + `Close` → `stdin_close`; `Kill` issues the `Signal` RPC and `Wait` unblocks on the signalled exit; ctx-cancel breaks the stream and `Wait` reports SIGKILL.
- `child_handle_test.go` — `newChildHandleFuncs`: `Kill` invokes/propagates; `Wait` surfaces `*ExitStatusError` unchanged; `Terminate` return-value precedence.
- `deliberate_kill_test.go` — `isDeliberateKill` accepts a real `*exec.ExitError` from a SIGKILLed local child (podman-path regression guard) and `*runtime.ExitStatusError{Signal: SIGKILL}`, rejects a non-signal `ExitStatusError`, an unrelated error, and nil.

Ledger-impact: none

Spec-impact: none. Refs RIG-2493

Co-authored-by: Matt Wilkinson <matt@rigel.build>
U4 of the frozen microVM Runner V2b plan (docs/designs/infra/runtime/compass-elastic-session-runtime/microvm-v2b-guest-supervisor-exec.md, Plan U4 / (c)/(d)/(e)). Fills the eight typed-error MicroVMRuntime stubs behind their frozen ContainerRuntime signatures against the V2a boot harness + the U3 GuestExec layer.

### Socket-path budget (CI fix, folded)

`e2eConfig` built its runroot with `t.TempDir()`, whose path embeds the test-function name. Under the 39-char `TestMicroVMExecStreamingKillSignalsExit` the widest per-session socket path — `<RunRoot>/microvm/<32-hex id>/virtiofsd.sock`, a 56-byte tail — reached 114 bytes, over the 107-byte Linux AF_UNIX `sun_path` cap, so virtiofsd's `bind(2)` failed EINVAL, the socket never appeared, and the boot timed out (`… did not appear within 10s`). `TestMicroVMLifecycleEndToEnd` (28-char name, 103 bytes) fit and booted. Production runroots are short and startup-budget-checked (`run.go` validateRuntimeDir); this is a pure harness artifact. Fix: `e2eConfig` uses a short `os.MkdirTemp("", "cvm")` runroot (cleaned via `t.Cleanup`), keeping the worst-case path well under the cap.

Refs RIG-2493

Co-authored-by: Matt Wilkinson <matt@rigel.build>
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u3-host-exec branch from 417292b to 3c87d57 Compare August 29, 2026 19:35
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u4-microvm-lifecycle branch from 9f07047 to 1975856 Compare August 29, 2026 19:37
Base automatically changed from compass-runner/rig-2493-u3-host-exec to main August 30, 2026 04:15
@mattwilkinsonn
mattwilkinsonn merged commit 6a2c05c into main Aug 30, 2026
17 of 19 checks passed
@mattwilkinsonn
mattwilkinsonn deleted the compass-runner/rig-2493-u4-microvm-lifecycle branch August 30, 2026 04:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants